协调器 (Supervisor) API 参考文档 #

本文档中引用的文件

目录 #

  1. 简介
  2. 函数签名与参数
  3. 核心架构
  4. 详细组件分析
  5. 状态管理
  6. 执行流程
  7. 使用示例
  8. 最佳实践
  9. 故障排除
  10. 总结

简介 #

CreateSupervisor 函数是 langgraphgo 中用于创建多代理系统协调器的核心函数。它实现了 Supervisor 模式，这是一种中央协调者模式，其中 supervisor 代理负责在多个专门化的工作者代理之间路由任务。这种模式特别适用于需要复杂工作流管理和任务分配的多代理系统。

核心功能特性 #

函数签名与参数 #

函数原型 #

func CreateSupervisor(model llms.Model, members map[string]*graph.StateRunnable) (*graph.StateRunnable, error)

参数详解 #

llms.Model（模型参数） #

类型：llms.Model

作用：用于决策的大型语言模型实例

关键特性：

实现细节：

members（成员映射参数） #

类型：map[string]*graph.StateRunnable

作用：成员代理的映射表，键为代理名称，值为对应的 StateRunnable 实例

设计原则：

内部处理：

Section sources

核心架构 #

整体架构图 #

graph TB
subgraph "Supervisor 协调器架构"
Supervisor["Supervisor 节点<br/>决策中心"]
subgraph "成员代理"
Agent1["MathExpert<br/>数学专家"]
Agent2["GeneralAssistant<br/>通用助手"]
AgentN["其他代理..."]
end
subgraph "状态管理"
StateSchema["状态架构<br/>MapSchema + AppendReducer"]
Messages["消息历史<br/>统一存储"]
end
subgraph "路由机制"
RouteTool["Route 工具<br/>决策接口"]
ConditionalEdge["条件边<br/>动态路由"]
end
end
Supervisor --> RouteTool
RouteTool --> Agent1
RouteTool --> Agent2
RouteTool --> AgentN
RouteTool --> ConditionalEdge
Agent1 --> Supervisor
Agent2 --> Supervisor
AgentN --> Supervisor
StateSchema --> Messages
Supervisor --> StateSchema

图表来源

状态架构设计 #

classDiagram
class StateSchema {
+RegisterReducer(key, reducer)
+MergeStates(states)
}
class MapSchema {
+reducers map[string]Reducer
+RegisterReducer(key, reducer)
+MergeStates(states)
}
class AppendReducer {
+Reduce(oldValue, newValue) interface
}
class StateRunnable {
+Invoke(ctx, state) interface
+Compile() StateRunnable
}
StateSchema <|-- MapSchema
MapSchema --> AppendReducer : "使用"
StateRunnable --> StateSchema : "依赖"

图表来源

Section sources

详细组件分析 #

Supervisor 节点实现 #

决策逻辑核心 #

Supervisor 节点是整个协调器的核心，负责分析当前状态并做出路由决策：

flowchart TD
Start([接收状态输入]) --> ValidateState["验证状态类型"]
ValidateState --> ExtractMessages["提取消息历史"]
ExtractMessages --> BuildRouteTool["构建路由工具"]
BuildRouteTool --> CreatePrompt["生成系统提示"]
CreatePrompt --> PrepareMessages["准备输入消息"]
PrepareMessages --> CallModel["调用 LLM 模型"]
CallModel --> CheckToolCall{"检查工具调用"}
CheckToolCall --> |无工具调用| HandleError["处理错误情况"]
CheckToolCall --> |有工具调用| ParseArgs["解析参数"]
ParseArgs --> ReturnDecision["返回决策结果"]
HandleError --> ReturnError["返回错误"]
ReturnDecision --> End([结束])
ReturnError --> End

图表来源

路由工具定义 #

路由工具是 Supervisor 做出决策的关键机制：

工具规格：

参数验证：

系统提示模板 #

Supervisor 使用精心设计的系统提示来指导 LLM 做出正确的决策：

提示内容结构：

  1. 角色定位：明确 Supervisor 的职责
  2. 可用资源：列出所有可用的代理成员
  3. 决策规则：强调使用 route 工具的重要性
  4. 输出格式：要求严格的工具调用格式

Section sources

成员代理节点 #

代理包装机制 #

每个成员代理都被包装成一个标准的 StateRunnable 节点：

sequenceDiagram
participant Supervisor as "Supervisor 节点"
participant AgentWrapper as "代理包装器"
participant MemberAgent as "成员代理"
participant State as "状态管理器"
Supervisor->>AgentWrapper : 调用代理
AgentWrapper->>State : 获取当前状态
State-->>AgentWrapper : 返回状态数据
AgentWrapper->>MemberAgent : Invoke(state)
MemberAgent->>MemberAgent : 执行业务逻辑
MemberAgent-->>AgentWrapper : 返回结果
AgentWrapper->>State : 合并状态更新
State-->>AgentWrapper : 确认合并
AgentWrapper-->>Supervisor : 返回最终状态

图表来源

状态传递策略 #

成员代理采用直接状态传递的方式：

Section sources

条件边路由机制 #

动态路由逻辑 #

条件边根据 Supervisor 的决策动态确定下一个执行节点：

flowchart TD
SupervisorDecision["Supervisor 决策"] --> CheckNext{"检查 next 字段"}
CheckNext --> |"FINISH"| EndWorkflow["结束工作流"]
CheckNext --> |代理名称| RouteToAgent["路由到指定代理"]
CheckNext --> |无效值| EndWorkflow
RouteToAgent --> ExecuteAgent["执行代理"]
ExecuteAgent --> ReturnToSupervisor["返回 Supervisor"]
ReturnToSupervisor --> SupervisorDecision
EndWorkflow --> WorkflowComplete["工作流完成"]

图表来源

路由条件实现 #

条件边的判断逻辑简洁而高效：

判断规则：

  1. 正常路由：当 next 等于某个代理名称时，路由到该代理
  2. 工作流结束：当 next 等于 “FINISH” 时，结束工作流
  3. 异常处理：其他情况下视为工作流结束

Section sources

状态管理 #

状态架构设计 #

MapSchema 架构 #

Supervisor 使用 MapSchema 作为状态架构的基础：

核心特性：

AppendReducer 机制 #

消息历史使用 AppendReducer 进行特殊处理：

处理逻辑：

状态流转过程 #

sequenceDiagram
participant User as "用户输入"
participant Supervisor as "Supervisor"
participant Agent as "成员代理"
participant State as "状态存储"
User->>State : 初始状态
State->>Supervisor : 启动工作流
Supervisor->>State : 分析对话历史
Supervisor->>Agent : 路由到代理
Agent->>State : 更新状态
State->>Supervisor : 返回状态更新
Supervisor->>Agent : 下一步决策
Agent->>State : 最终状态
State-->>User : 完整对话历史

图表来源

Section sources

执行流程 #

初始化阶段 #

图表构建过程 #

flowchart TD
Start([开始创建]) --> CreateGraph["创建 StateGraph"]
CreateGraph --> SetupSchema["设置状态架构"]
SetupSchema --> ExtractMembers["提取成员列表"]
ExtractMembers --> AddSupervisor["添加 Supervisor 节点"]
AddSupervisor --> AddAgents["添加成员代理节点"]
AddAgents --> SetEntryPoint["设置入口点"]
SetEntryPoint --> AddConditionalEdge["添加条件边"]
AddConditionalEdge --> AddLoopEdges["添加循环边"]
AddLoopEdges --> Compile["编译为 StateRunnable"]
Compile --> End([返回结果])

图表来源

状态初始化 #

初始状态结构：

initialState := map[string]interface{}{
    "messages": []llms.MessageContent{
        llms.TextParts(llms.ChatMessageTypeHuman, "用户请求"),
    },
}

状态字段说明：

执行阶段 #

主循环流程 #

flowchart TD
EntryPoint["入口点: Supervisor"] --> SupervisorExec["执行 Supervisor"]
SupervisorExec --> Decision{"决策类型"}
Decision --> |"代理名称"| AgentExec["执行对应代理"]
Decision --> |"FINISH"| EndExec["结束执行"]
AgentExec --> AgentResult["代理结果"]
AgentResult --> SupervisorExec
EndExec --> Complete["执行完成"]

图表来源

并发执行机制 #

StateGraph 支持并发节点执行：

并发特性：

Section sources

使用示例 #

基础使用示例 #

以下展示了如何创建和使用 Supervisor 协调器的基本流程：

代理创建 #

// 创建数学专家代理
mathAgent, err := prebuilt.CreateReactAgent(model, []tools.Tool{CalculatorTool{}})
if err != nil {
    log.Fatal(err)
}

// 创建通用助手代理
generalAgent, err := prebuilt.CreateReactAgent(model, []tools.Tool{})
if err != nil {
    log.Fatal(err)
}

协调器配置 #

members := map[string]*graph.StateRunnable{
    "MathExpert":       mathAgent,
    "GeneralAssistant": generalAgent,
}

supervisor, err := prebuilt.CreateSupervisor(model, members)
if err != nil {
    log.Fatal(err)
}

执行流程 #

// 设置初始状态
initialState := map[string]interface{}{
    "messages": []llms.MessageContent{
        llms.TextParts(llms.ChatMessageTypeHuman, "计算 10 * 5 并告诉我关于结果的笑话"),
    },
}

// 执行工作流
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := supervisor.Invoke(ctx, initialState)
if err != nil {
    log.Fatal(err)
}

高级使用场景 #

多层代理协作 #

// 创建多层级代理系统
researchAgent, _ := prebuilt.CreateReactAgent(model, []tools.Tool{ResearchTool{}})
analysisAgent, _ := prebuilt.CreateReactAgent(model, []tools.Tool{AnalysisTool{}})
reportAgent, _ := prebuilt.CreateReactAgent(model, []tools.Tool{ReportTool{}})

multiLevelMembers := map[string]*graph.StateRunnable{
    "Researcher": researchAgent,
    "Analyst":    analysisAgent,
    "Reporter":   reportAgent,
}

multiLevelSupervisor, _ := CreateSupervisor(model, multiLevelMembers)

条件路由示例 #

// 基于任务类型的条件路由
conditionalSupervisor, _ := CreateSupervisor(model, map[string]*graph.StateRunnable{
    "DataProcessor": dataProcessor,
    "TextGenerator": textGenerator,
    "ImageCreator":  imageCreator,
})

// Supervisor 将根据任务内容自动选择合适的代理

Section sources

最佳实践 #

代理设计原则 #

代理职责分离 #

单一职责原则：

代理命名规范 #

命名建议：

状态管理最佳实践 #

状态架构设计 #

推荐模式：

错误处理策略 #

容错机制：

性能优化建议 #

并发执行优化 #

优化策略：

LLM 调用优化 #

调优建议：

故障排除 #

常见问题及解决方案 #

Supervisor 决策失败 #

问题症状：

解决方案：

  1. 检查 LLM 模型配置
  2. 验证路由工具定义
  3. 确认系统提示的清晰度

状态同步问题 #

问题症状：

解决方案：

  1. 验证状态架构配置
  2. 检查状态合并逻辑
  3. 确认代理状态传递方式

循环依赖问题 #

问题症状：

解决方案：

  1. 检查条件边配置
  2. 验证 “FINISH” 路径
  3. 添加递归深度限制

调试技巧 #

状态监控 #

// 启用调试输出
fmt.Printf("Debug: Current state: %+v\n", currentState)
fmt.Printf("Debug: Supervisor decision: %s\n", decision)

执行跟踪 #

// 添加执行时间跟踪
startTime := time.Now()
result, err := supervisor.Invoke(ctx, initialState)
elapsedTime := time.Since(startTime)
fmt.Printf("Execution time: %v\n", elapsedTime)

Section sources

总结 #

CreateSupervisor 函数为 langgraphgo 提供了强大而灵活的多代理系统协调能力。通过智能的路由决策、统一的状态管理和动态的工作流控制，它能够有效地管理复杂的多代理交互场景。

核心优势 #

  1. 智能化决策：利用 LLM 的推理能力做出最优路由决策
  2. 灵活的架构：支持动态添加和移除代理成员
  3. 状态一致性：确保所有代理共享统一的状态视图
  4. 优雅的终止：通过 “FINISH” 机制实现工作流的优雅结束

应用场景 #

发展方向 #

随着 AI 技术的发展，Supervisor 模式将在以下方面继续演进：

通过深入理解和正确使用 CreateSupervisor 函数，开发者可以构建出更加智能和高效的多代理系统，为用户提供更好的服务体验。